MacWorld 1999 July/Macworld (1999-07).dmg/Serious Software/OpenWorld demo 2.0/Development/Headers/WSAPI.h

Text File | 1998-08-09 | 40KB | 740 lines

//WSAPI.h

/*
WebSTAR API Interface, v1.1
Copyright ©1996, StarNine Techologies, Inc. All rights reserved.

This file defines the public interface between the WebSTAR plug-in framework and
user-defined plug-in routines.

*/

#ifndef WSAPI_Included
#define WSAPI_Included 1

#if GENERATINGPOWERPC
#pragma options align=mac68k
#endif

#ifdef __cplusplus
extern "C" {
#endif

#define WSAPI_VERSION    (unsigned long) 0x01010000    //Do NOT modify this value
#define WSAPI_MAC    1


#include <AppleEvents.h>

extern unsigned long wsapi_lib_version;    // the version of the WSAPI library code this plug-in is linked with. Useful
                                        // for making sure your plug-in was built with libs that match the interfaces, etc.


// enums that identify what type of server is "glued" to the WSAPI plug-in. Useful for determining the callback
// and parameter feature set that will be available at run-time. See wsapi_glue_type variable below.
typedef enum {
    WSAPI_Mac_Glue,        //plug-in is built as a WebSTAR Mac plug-in
    WSAPI_PC_Glue,        //plug-in is built as a WebSTAR 95 or NT plug-in
    NSAPI_Glue,            //plug-in is built as a Netscape plug-in
    ISAPI_Glue            //plug-in is built as a Microsoft plug-in
} WSAPI_Server_Glue_Type;

extern WSAPI_Server_Glue_Type wsapi_glue_type;    //what type of glue libraries are being used by the plug-in?

#define WSAPI_NAME_SIZE    32
#define WSAPI_FILE_NAME_SIZE     256            /*size of text representations of file paths*/
#define WSAPI_VERSION_STR_SIZE    12            /*size of the version string returned in the init message pb*/
#define WSAPI_INDEX_SIZE 64                    //the maximum length of index selectors used with Get and SetIndexedParameter

#define WSAPI_IPC_CONNECTION_MASK 0x00003FFF //See WSAPI_SendIPCMessage below

//  Not completely implemented yet. You may set these flags, but WebSTAR ignores them for now.
//  Flags that define capabilities that the plug-in can perform or services it wants to take advantage of
//  Used in the "capabilities" field of the Init message's PB record. Your plug-in should OR the appropriate
//  flags together and assign them to the capabilities field which is returned to the server at the completion of the
//    Init message handling. The server will use these flags to determine if a user has misconfigured your plug-in for
//    a role that it cannot support.

#define capISAPISubset        (unsigned long) 0x00000001        //restrict plug-in to ISAPI compatible calls - not implemented yet
#define capCGI                (unsigned long) 0x00000002        //plug-in is willing to operate as a normal CGI plug-in
#define capPreProcessor        (unsigned long) 0x00000004        //p.i. will work as a preprocessor
#define capPostProcessor    (unsigned long) 0x00000008        //p.i. will work as a postprocessor
#define capLogging            (unsigned long) 0x00000010        //p.i. will receive logging and status messages - not implemented yet
#define capSecurity            (unsigned long) 0x00000020        //p.i. will perform security checks - not implemented yet
#define capNSAPISubset        (unsigned long) 0x00000040        //restrict plug-in to NSAPI compatible calls - not implemented yet

/*****************************************************************************/
/*##     Important note to developers: Not all servers will implement all of these parameters.
        It is up to individual server implementors to decide which parameters will be supported,
        since some of these are WebSTAR-specific. It is possible that other server implementors
        will add additional parameters beyond the ones supported by WebSTAR as well.
 */

/** Keywords used to get/set WebSTAR parameters with WSAPI_Get/SetParameter **/
/** Note that these have the same definitions and formats as AppleEvent parameters
    of the same value. With the exceptions noted below, all parameters are of type
    "typeChar." The two numeric values below should be noted.
**/
typedef enum {
    piPathArgKeyword        = '----',
    piSearchArgKeyword        = 'kfor',
    piUserKeyword            = 'user',
    piPasswordKeyword        = 'pass',
    piFromUser                = 'frmu',
    piAddressKeyword        = 'addr',
    piPostKeyword            = 'post',
    piMethodKeyword            = 'meth',
    piServerName            = 'svnm',
    piServerPort            = 'svpt',    //typeShortInteger - IP port (e.g, 80)
    piScriptName            = 'scnm',
    piContentType            = 'ctyp',
    piContentLength            = 'CLen',    //typeLongInteger - the content-length header field (if any) from HTTP request
    piRefererKeyword        = 'refr',
    piUserAgentKeyword        = 'Agnt',
    piActionKeyword            = 'Kact',
    piActionPathKeyword        = 'Kapt',
    piClientIPAddress        = 'Kcip',    //typeLongInteger - 4 byte IP address
    piFullRequestKeyword    = 'Kfrq',

    //new for plug-ins only
    piFileMIMEType            = 'Mime',    // The MIME type of the URL in piScriptName
    piServerField            = 'SvFd',    // The HTTP header field for this server. e.g., "Server: WebSTAR/1.3 ID/22"
    piServerDirectoryPath    = 'SPth',    // A C string representing the complete (machine-specific) path name of the server's working directory
    piURLPhysicalPath        = 'UPth',    // If the URL represents an actual file in the file system, this parameter contains its name relative to the server's root.
    piIfModifiedSince        = 'IfMS',    // short. True if the file has been modified since last retrieval or if modification cannot be determined. False if unchanged.
    piIfModifiedDate        = 'IfMD',    //## typeChar, R/O, if-modified-since date string from HTTP request header
    piCurrentRealm            = 'CRlm',    // typeChar, 256 max. The realm (if any) that the requested URL belongs to.
                                        // WSAPI_E_RequestFailed will be returned by GetParameter if this value isn't defined for the current request.
    piURLFileRef            = 'Pufr',    //## typeFSS, R/0, Server-specific reference to file in the native O/S. On the
                                        //  Mac with WebSTAR, this is a FSSpec to actual file being requested if it
                                        //  really exists on disk. Nonexistent files will have a FSSpec that has all
                                        //  fields set to zero and the name field will be empty.
    //******************************
    //log- and status-related values
    piConnectionID            = 'LCID',    //long - unique # for each connection for this run of the server
    piServerUniqueID        = 'LSID',    //long - unique # across all current server invocations on this machine
    // note: the value of the WebSTAR message-id: field can be generated with the following C printf format,
    //   using the values of the preceding two properties:
    //  printf ("<%0lx.%ld@%s>", serverUniqueIDVar, connectionIDVar, hostnameVar);

    //*****************************
    // The following parameters are read-only and represent information present in the server's
    // status display and/or the information broadcast to remote logging processes.
    piTotalConnections        = 'STCn',    // long. Total connections the server has received since it started up
    piCurrentUserLevel        = 'SCLd',    // short. Current number of users connected to the server at this time
    piHighestUserLevel        = 'SMLd',    // short. Max number of users ever connected to the server at once
    piCurrentFreeMemory        = 'SFMm',    // long. Amount of free memory available to the server process
    piMinimumFreeMemory        = 'SMFM',    // long. Minimum amount of free memory that was ever available to the server process
    piTotalConTimeouts        = 'STTm',    // short. Total number of client connections that timed out before completion
    piTotalConBusies        = 'STBz',    // short. Total number of client connections refused because the server was too busy
    piTotalConDenied        = 'STDn',    // short. Total number of client connections denied by domain name or IP address
    piTotalBytesSent        = 'TByt',    // long. Total number of bytes sent by the server
    piUpSinceDate            = 'SUpS',    // C string. Date & time the server was launched; Format, MM/DD/YY:HH:MM
    piPluginAdminInfo        = 'Padm',    //##typeChar, R/O, text block containing info on each plug-in currently installed
                                        //    tab separated syntax of each line is: <name> <version> <Admin URL path><cr>

    //******************************
    // ##These four parameters describe the plug-in environment, including the physical location of plug-ins
    // and information about each parameter that can be manipulated at runtime to determine range checks, types,
    // string representations, etc. See the W*API docs for details on the format of the piPluginParamInfo data structure.

    piPluginParamInfo        = 'Pipi',    //##typeLong, R/O, pointer to a W*API-specific data structure describing plug-in parameter semantics
    piPluginParamCount        = 'Pipc',    //##typeSMInt, R/O, count of the number of W*API parameters in piPluginParamInfo
    piPluginDirPath            = 'Pdph',    //##typeChar, R/O, full path to the plug-ins folder
    piPluginDirFSSpec        = 'Pdfs',    //##typeFSS, R/O, platform-specific file system reference to plug-ins folder

    //******************************
    //the following 3 values are only guaranteed to be set AFTER a connection has been completed
    //  and logged. (i.e., only access them from a post-processor plug-in.)
    piTransferResult        = 'LTRs',    //OK, PRIV, or ERR! string, depending on transfer result
    piBytesSent                = 'LByt',    //number of bytes written to the HTTP client
    piTransferTime            = 'LTrT',    //number of ticks it took from connection open to close

    //******************************
    // WebSTAR properties below here.
    //  These match the definitions in the WebSTAR AETE resource.

    // The following values are all global WebSTAR properties.

    piDumpBufSize            = 'Dbuf',    //typeLongInteger
    piPigDelay                = 'PigD',    //typeSMInt
    piMaxUsers                = 'MaxU',    //typeSMInt
    piNoDNS                    = 'Ndns',    //typeSMInt
    piTimeOut                = 'TimO',    //typeSMInt
    piMaxListens            = 'MaxL',    //typeSMInt
    piLogging                 = 'Plog',    //typeSMInt
    piVerboseMessages        = 'Pvrb',    //typeSMInt
    piRefuseConnections        = 'Pcon',    //typeSMInt
    piHideWindow            = 'Phid',    //typeSMInt
    piDefaultMIMEType        = 'Pmim',    //typeChar
    piPort                    = 'Pprt',    //typeSMInt
    piIndexFile                = 'Pixf',    //typeChar
    piErrorFile                = 'Perf',    //typeChar
    piLogFile                = 'Plgf',    //typeChar
    piNoAccessFile            = 'Pnaf',    //typeChar
    piSuffixMappings        = 'Psuf',    //typeChar
    piAllowDeny                = 'Pa/d',    //typeChar
    piAllowDenyByRealm        = 'PADr',    //##typeChar - R/W, NOTE!! This is an indexed value and you must use the
                                        // WSAPI_GetIndexedParameter or WSAPI_SetIndexedParameter call to manipulate it. The Index is
                                        // the name of the realm to get or set allow/deny info for.
    piRealms                = 'Prlm',    //typeChar
    piActions                = 'Pact',    //typeChar
    piLogFormat                = 'Plfm',    //typeChar
    piPreProcessor            = 'Ppre',    //typeChar
    piPostProcessor            = 'Ppst',    //typeChar
    piVersionNumber            = 'Pvrs',    //typeChar
    piReportDelay            = 'Prdl',    //##typeSMInt - R/W, amount of time in seconds between status report events
    piCacheFlush            = 'Pcfl',    //##typeSMInt - W/O, setting this flag indicates the server should flush any
                                        // cached data. A plug-in receiving this parameter to a WSAPI_ServerStateChanged
                                        // message should interpret it as a signal for the plug-in to flush any cached data
                                        // it retains from the local file system.
    piFileInfoCacheSize        = 'Pfic',    //##typeLong - R/W, amount of memory to allocate to file info caching
    piKeepAliveConnections    = 'Pkac',    //##typeSMInt- R/W, number of connections per client to keep alive
    piKeepAliveTime            = 'Pkat',    //##typeSMInt- R/W, seconds to keep alive idle client connections
    piServerCName            = 'Pscn',    //##typeChar - R/W, canonical name of server to be used in HTTP responses, regardless of DNS name
    piCGIBinOnly            = 'Pcbo',    //##typeSMInt - R/W, flag determining if CGIs will be executed from the /cgi-bin folder only
    piServiceAddress        = 'Pisa'    //##typeLong - R/W, INDEXED VALUE, table of registered service addresses
                                        // This is a complicated parameter. You should refer to the W*API documentation for details.
                                        // The index is the name of the service whose address you wish to register or retrieve.
} WSAPI_ParamKeywords;

/*****************************************************/
//    Parameter block information

typedef unsigned long WSAPI_Stream, *WSAPI_StreamPtr; //type for IP callbacks in network stuff below

//messages sent to plug-in dispatcher
typedef enum {
    WSAPI_Init,
    WSAPI_Shutdown,
    WSAPI_Idle,
    WSAPI_Run,
    WSAPI_Emergency,
    WSAPI_ServerStateChanged,
    WSAPI_Register,
    WSAPI_AccessControl,    //##
    WSAPI_Filter            //##
} WSAPI_Command;

//sub-messages sent to plug-in dispatcher in the "role" field when message is "WSAPI_Run"
typedef enum {
    WSAPI_CGI_Role,                //running as a normal CGI replacement
    WSAPI_PreProcessor_Role,    //acting as a pre-processor
    WSAPI_PostProcessor_Role,    //acting as a post-processor
    WSAPI_Logging_Role,            //receiving log info
    WSAPI_Security_Role,        //performing an access authorization
    WSAPI_Error_Role,            //handling bad URL requests
    WSAPI_NoAccess_Role,        //handling requests denied by IP or domain
    WSAPI_Index_Role            //handing a request for the default file
} WSAPI_Run_Role;

//descriptor type used to extract various named parameters available to plug_ins
typedef void *WSAPI_DescPtr;

/** structure types making up the CommandPB parameter block **/

typedef struct {        // now used by both init and register messages
    short resRef;        //in - reference number of plug-in's resource file
    char pluginName [WSAPI_NAME_SIZE]; //##in/out - the unique name that identifies this plug-in. Initialized to file name.
    unsigned long capabilities; // out - flags that indicate functions the plug-in can perform or services it wants
    //## these fields should be filled in during the Register message
    char version [WSAPI_VERSION_STR_SIZE]; //##out - string representation of the plug-in's version, e.g., "1.0b1"
    char adminURL [WSAPI_FILE_NAME_SIZE]; //##out - path portion ONLY of URL to configure plug-in, e.g. "/admin.plugsuffix"
} WSAPI_InitPB;

typedef struct {
    short unused;         //not sure what args shutdown needs to send in and out yet
} WSAPI_ShutdownPB;

typedef struct {
    unsigned long ticksToSleep;    //out - how long to sleep before WebSTAR's idle handler calls again
} WSAPI_IdlePB;

typedef struct {
    WSAPI_Run_Role role;    //what is this invocation supposed to do? be a CGI, preprocessor, etc?
} WSAPI_RunPB;

typedef struct {
    short unused;
} WSAPI_EmergencyPB;

typedef struct {
    WSAPI_ParamKeywords    whichParam;        // contains the WSAPI_ParamKeywords (parameter) value that has changed
} WSAPI_StateChangedPB;

typedef struct {
    short    grantAccess;        //## boolean flag. If true, the server will process the URL as normal
    short    authRequired;        //## boolean flag. If true, the server will require password access
} WSAPI_AccessControlPB;

typedef struct {                //## server sends this structure with the WSAPI_Filter message
    char *request;                //## request contains a pointer to the read-only HTTP request data (not including object body)
    short requestLength;        //## length in characters of the request. Data beyond length bytes should not be modified!
    char *newRequest;            //## null initially. setting pointer to new request data (allocated by you with WSAPI_AllocateMemory ONLY!)
                                //##   forces server to replace original request with data you generate for the request instead
    short newRequestLength;        //## zero initially. length in characters of the new request you create.
} WSAPI_FilterPB;

typedef union {
    WSAPI_InitPB         init;            // used by both register and init messages
    WSAPI_ShutdownPB     shutdown;
    WSAPI_IdlePB        idle;
    WSAPI_RunPB            run;
    WSAPI_EmergencyPB    emergency;
    WSAPI_StateChangedPB stateChanged; // see above
    WSAPI_AccessControlPB accessControl; //##
    WSAPI_FilterPB        filter; //##
} WSAPI_PB_Union;

typedef struct {
    long api_version;            //in - what version of API does the server support?
    void *api_data;                //in - private data. DON'T TOUCH!
    WSAPI_Command command;        //in - what operation is the plug-in to perform?
    WSAPI_PB_Union param;
} WSAPI_CommandPB, *WSAPI_CommandPBPtr;

// record for holding pending IPC stuff
#if WSAPI_MAC

typedef struct {
    AppleEvent theAppleEvent;
    AppleEvent reply;
    long handlerRefcon;
} WSAPI_IPC_Result, *WSAPI_IPC_ResultPtr;

#else

typedef struct {
    void *theIPCMsg;
} WSAPI_IPC_Result, *WSAPI_IPC_ResultPtr;

#endif

//*******************************
//##Definitions for the piPluginParamInfo data structure

#define WSAPI_PARAM_SIZE 32

typedef struct piparam_table_struct {
    WSAPI_ParamKeywords param;        //one of the enums from above
    char name[WSAPI_PARAM_SIZE];    //case-sensitive string representation of the parameter's name
    char index[WSAPI_PARAM_SIZE];    //"name" of the index field. usually maps to a HTML form field name
    OSType type;                    //4 character (long) parameter type
    short mode;                        //bit field describing read/write access. masks: read = 2, write = 1
    long lower;                        //lower bound for range checking integer parameters
    long upper;                        //upper bound for range checking. If less than lower bound, no range is specified
    void *extra_info;                //reserved for future expansion
} WSAPI_ParamInfo, *WSAPI_ParamInfoPtr;


//*******************************
/** Error codes returned by various WSAPI calls **/

typedef enum {
    WSAPI_I_NoErr,                //normal completion code, synonymous with noErr
    WSAPI_E_MessageNotHandled,    //return value indicates the command message wasn't processed
    WSAPI_E_ParameterNotFound,    //requested parameter descriptor did not exist
    WSAPI_E_InsufficientMemory,    //not enough memory to perform requested operation
    WSAPI_E_Unimplemented,        //requested function is not yet implemented or isn't available for this version of WSAPI
    WSAPI_E_HTTPConnectionGone,    //the client connected to this thread has closed the connection
    WSAPI_E_BadCommandPtr,        //commandPtr that was passed was null or invalid
    WSAPI_E_CantOpenStream,        //TCP/IP stream couldn't be created or opened
    WSAPI_E_BufferTooBig,        //data buffer was too large for the callback to process
    WSAPI_E_NameLookupFailed,    //the domain name resolver failed to resolve the requested name
    WSAPI_E_NullDescriptor,        //10, a null descriptor, or one with no data pointer was passed when real data was required
    WSAPI_E_UnspecifiedError,    //some unknown error happened
    WSAPI_E_BadArgument,        //one of the arguments (usually a pointer) passed to a callback was invalid
    WSAPI_E_CantModifyData,        //an attempt was made to modify read-only data
    WSAPI_E_DescriptorTooSmall,    //user-supplied storage for a descriptor is too small for the data being assigned to it
    WSAPI_E_HTTPConnectionErr,    //plug-in attempted to read from a closed or non-existent HTTP stream, or some other IP-related error occurred.
    WSAPI_E_WrongRoleForCall,    // plug-in tried to make a callback that is inappropriate for the current WSAPI_Command
    WSAPI_E_RequestFailed,        // whatever request the plug-in was making of the server failed to complete successfully
    WSAPI_E_IPCMsgPending,        // an attempt was made to send an IPC message while one was already in progress
    WSAPI_E_IPCNoMsgPending,    // an attempt was made to receive IPC message results when no message was in progress
    WSAPI_E_Timeout,            //20, requested operation took too long and timed out before being completed
    WSAPI_I_NoPermission,        // current user doesn't have permissions for realm; other security violation
    WSAPI_E_ParameterIndexedOnly,//the requested parameter can only be accessed as an indexed parameter
    WSAPI_E_IndexedValueNotFound//the item specified by the index was not present in the requested object
} WSAPI_ErrorCode;

/** TCP/IP conection status codes **/

typedef enum {
    WSAPI_IP_Closed,     //connection is closed or terminated. plug-in should stop processing
    WSAPI_IP_Open,         //connection is open
    WSAPI_IP_Data,        //connection is open and has unread data on it
    WSAPI_IP_Unknown    //an unknown or unspecified error occurred
} WSAPI_ConnectionStatus;

/** ##Misc. W*API type definitions **/

typedef char WSAPI_IndexString [WSAPI_INDEX_SIZE];    //index selector used by WSAPI_Get and SetIndexedParameter
typedef WSAPI_IndexString *WSAPI_IndexStringPtr;

/********************************************************************/
//WSAPI Framework Function prototypes

// You may call any of the following functions from inside your plug-in to
// have WebSTAR perform the requested function.

/*************************/
/**  Memory Management  **/

void *WSAPI_AllocateMemory (WSAPI_CommandPBPtr pb, long size);
/*     Allocates and returns a pointer to "size" bytes of data. Returns NULL if
    memory allocation fails.
    Do NOT use any other techniques to allocate memory within your plug-in code.
    All memory should be allocated using this call and disposed of using the
    corresponding WSAPI_FreeMemory call.
*/

void WSAPI_FreeMemory (WSAPI_CommandPBPtr pb, void *data);
/*    Deallocates a block of memory originally allocated with WSAPI_AllocateMemory. Do NOT mix
    and match WSAPI_AllocateOSMemory and WSAPI_FreeMemory or vice versa!!!
*/

void *WSAPI_AllocateOSMemory (WSAPI_CommandPBPtr pb, long size);
/*      Allocates and returns an O/S-specific memory accessor (e.g., a Handle under Mac O/S)
    to "size" bytes of data. Returns NULL if memory allocation fails.
    Do NOT use any other techniques to allocate memory within your plug-in code.
    All memory should be allocated using this call and disposed of using the
    corresponding WSAPI_FreeOSMemory call.
*/

void WSAPI_FreeOSMemory (WSAPI_CommandPBPtr pb, void *data);
/*     Deallocates a block of memory originally allocated with WSAPI_AllocateOSMemory. Do NOT mix
    and match WSAPI_AllocateMemory and WSAPI_FreeOSMemory or vice versa!!!
*/

/*************************/
/** Process Management  **/

WSAPI_ErrorCode WSAPI_YieldTime (WSAPI_CommandPBPtr pb, long ticksToYield);
/*    Yields time to WebSTAR, allowing other threads, plug-ins, and processes to
    have access to the CPU. ticksToYield is only a suggestion to WebSTAR about how
    long to wait (in ticks) before resuming this thread. Control may return sooner or later
    than the time specified. This routine MUST be called if you are performing any
    processing that takes more than a few milliseconds, involves I/O of any significant
    amount, or would otherwise prevent normal operation of other apps in the
    MultiFinder environment. This call is essentially equivalent to the Thread Manager's
    YieldToAnyThread call.
*/

WSAPI_ErrorCode WSAPI_RequestIdleTime (WSAPI_CommandPBPtr pb, unsigned long ticksToSleep);
/*    This routine registers your plug-in with WebSTAR's idle time dispatcher. Plug-ins
    registered this way will have the WSAPI_Idle command sent to them at an interval
    approximating ticksToSleep. Plug-ins are called in the context of the idle dispatcher
    and will not have access to an active HTTP connection or associated data.
    This routine is useful for performing periodic global tasks within your plug-in.
*/

/*************************/
/** Networking Services **/

WSAPI_ErrorCode WSAPI_SendHTTPData (WSAPI_CommandPBPtr pb, void *data, long dataLen);
/*    Sends an arbitrarily large buffer of data to a HTTP client over an open HTTP connection.
    This implements a raw data stream to the client, allowing you to generate your own HTTP
    header and content, similar to what current CGI applications do now. The difference is
    that your data is going back in real time and you can send as much as you'd like.
    "data" is a pointer to a buffer containing any type of data. dataLen is the number of
    bytes within this buffer to transmit. No translation is performed by WebSTAR on data.
    You are responsible for disposing of the data pointer after this call returns, if
    necessary. Avoid sending many, small buffers of data with this routine if possible.

    NOTE: If this call ever returns a non-zero return value, you should terminate any
    processing and return control to WebSTAR immediately. This is an indication
    that the client has disconnected and WebSTAR needs to clean up the connection.
*/

WSAPI_ErrorCode WSAPI_ReadHTTPData (WSAPI_CommandPBPtr pb, void *data, long *dataLen);
/*    Reads data from the HTTP stream. Useful for reading and processing large POST args,
    etc., like file uploads. You must supply storage for data and pass in the maximum amount of
    data to be returned in the dataLen parameter. WSAPI will return up to dataLen bytes in data
    and will set dataLen to the actual amount of data returned.

    Use the WSAPI_HTTPConnectionStatus below to determine if data is pending on the HTTP connection, etc.

    IMPORTANT! If a pre-processor reads the HTTP object body data from a connection, that data
    will NOT be available to downstream plug-ins or CGIs should the pre-processor decide not to
    handle the URL. That means no post args for CGIs, etc. In general, it's bad form for any
    role other than CGI, Error, NoAccess, or Index to make this call. Specific cases excepted.

    Additional note, the piPostKeyword parameter can be used to repeatedly access the first 24k bytes
    of this data without any side effects to downstream consumers or the IP data stream.
*/

WSAPI_ErrorCode WSAPI_HTTPConnectionStatus (WSAPI_CommandPBPtr pb, WSAPI_ConnectionStatus *status);
/*    Returns the status of the HTTP connection associated with the thread that this call is made
    from. Obviously, this is an invalid call to make from any message handler except the RUN
    message. Returns the appropriate WSAPI_ConnectionStatus in the status parameter.
*/

//Generic Open, Close, Send, and Receive - TBS

WSAPI_ErrorCode WSAPI_OpenStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, unsigned long ip_addr, unsigned short ip_port);
/*
    Returns a Stream pointer to an open connection to the host and port specified. ip_addr is a
    long integer representation of the host address, as returned from the DNS routines. If an error is returned,
    the stream was not successfully created.
*/

WSAPI_ErrorCode WSAPI_CloseStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream);
/*
    Gracefully closes a connection opened using OpenStream.
*/

WSAPI_ErrorCode WSAPI_ReadStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, void *data, long *dataLen);
/*
    Reads up to *dataLen bytes from the specified stream. *dataLen contains the actual number of bytes read,
    which may be less than the number requested.
*/

WSAPI_ErrorCode WSAPI_WriteStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, void *data, long dataLen);
/*
    Writes dataLen bytes of data to the specified stream. If dataLen is too large, an error will be returned.
    Generally, you should never try to write more data than the maximum dump_buf_size for WebSTAR in one operation.
*/

WSAPI_ErrorCode WSAPI_StatusStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, WSAPI_ConnectionStatus *status, long *pending);
/*
    Returns the status of the specified stream (open, closed, data pending) and the amount of unread data. Under
    OpenTransport, the pending flag will simply be positive if data exists to be read.
*/

WSAPI_ErrorCode WSAPI_IPNameToAddr (WSAPI_CommandPBPtr pb, char *name, unsigned long *addr);
/*
    Converts the domain name or dotted IP address in "name" into a 4 byte IP address for use in the OpenStream call.
*/


/*************************/
/**  Utility Functions  **/

WSAPI_ErrorCode WSAPI_GetParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam,
                                    WSAPI_DescPtr *descriptor);
/*    Use this routine to obtain descriptors that reference named WebSTAR data elements. These
    elements are generally equivalent to the AppleEvent parameters passed to CGIs. However,
    certain WebSTAR properties will also be made available via this interface. See the list
    of available parameters and properties above (WSAPI_ParamKeywords).

    You must always dispose of any descriptors returned by WSAPI_GetParameter.

    If the value for a parameter is undefined at the time the call is made, but the paramter is a legal
    one to request, WSAPI_GetParamter will return WSAPI_E_RequestFailed. If the parameter cannot be requested
    at the time the call is made (because of role or message conflicts), the WSAPI_E_WrongRoleForCall error
    will be returned.

*/

WSAPI_ErrorCode WSAPI_SetParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam,
                                    WSAPI_DescPtr descriptor);
/*     Use this routine to set server parameters to the value specified in the descriptor.
    You need to create the descriptor first, using WSAPI_NewDescriptor. Then use WSAPI_SetDescriptor
    to insert values into the new descriptor before passing it to WSAPI_SetParameter.
*/

WSAPI_ErrorCode WSAPI_GetIndexedParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam,
                                    WSAPI_IndexStringPtr index, WSAPI_DescPtr *descriptor);
/*    ## Use this routine to obtain descriptors that reference indexed items in a named server data element.
    These elements consist of values with repeating items that are specified by a unique index value
    for each item. Attempting to use this routine on a non-indexed parameter will simply return the
    value of the scalar parameter. The index selector is case-insensitive. pb may be null when appropriate.

    You must always dispose of any descriptors returned by WSAPI_GetIndexedParameter.

    If the value for a parameter is undefined at the time the call is made, but the parameter is a legal
    one to request, WSAPI_GetIndexedParameter will return WSAPI_E_RequestFailed. If the parameter cannot be
    requested at the time the call is made (because of role or message conflicts), the WSAPI_E_WrongRoleForCall
    error will be returned.

*/


WSAPI_ErrorCode WSAPI_SetIndexedParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam,
                                    WSAPI_IndexStringPtr index, WSAPI_DescPtr descriptor);
/*    ## Use this routine to set indexed items of server elements to the value specified in the descriptor.
    You need to create the descriptor first, using WSAPI_NewDescriptor. Then use WSAPI_SetDescriptor
    to insert values into the new descriptor before passing it to WSAPI_SetIndexedParameter.
    Attempting to use this routine on a non-indexed parameter will simply set the
    value of the scalar parameter. The index selector is case-insensitive. pb may be null when appropriate.
*/

WSAPI_ErrorCode WSAPI_NewDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr *descriptor,
                                        OSType dataType, void *data, unsigned long dataSize);

/*  Pass a pointer to a descriptor pointer and WSAPI will allocate it, defining the data type, size and content.
    If the data pointer is null when passed, a data block of dataSize will be allocated anyway and you
    can assign values to the descriptor later using WSAPI_SetDescriptor. If you supply data storage and pass
    it in the data parameter, you are responsible for deallocating the storage later. If you pass NULL, the
    data is allocated and deallocated by WSAPI automatically.
*/

WSAPI_ErrorCode WSAPI_DisposeDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr *descriptor);

/*  Pass a pointer to a descriptor pointer that needs deallocation and WSAPI will deallocate it.
*/

WSAPI_ErrorCode WSAPI_GetDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr descriptor,
                                        OSType *dataType, void *data, unsigned long *dataSize);
/*  Pass a descriptor pointer and WSAPI will return specific information about the descriptor. You
    must provide storage for all pointers. The data pointer must be large enough to hold the number of
    bytes returned in the dataSize parameter. If the data pointer is NULL, WSAPI still returns the type
    and size information, allowing you to then allocate an appropriately sized data container and
    call WSAPI_GetDescriptor again with a non-null data pointer. When called, dataSize should be initialized
    to the maximum size of your data buffer. On return, it will contain the actual amount of data stored
    in the data buffer.
*/


WSAPI_ErrorCode WSAPI_SetDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr descriptor,
                                    void *data, unsigned long dataSize);
/*  Sets the data and size portions of an existing descriptor pointed to by "descriptor".
    Data is copied from the "data" parameter into the storage allocated inside the descriptor.
    If the existing data area allocated inside the descriptor is too small, the server will attempt
    to resize it to be large enough for dataSize bytes of data. But your plug-in should be prepared
    to handle a failure if the storage cannot be resized.
*/

WSAPI_ErrorCode WSAPI_RegisterAction (WSAPI_CommandPBPtr pb, char *actionTag, char *pluginName);
/*     Your plug-in must call this routine in response to the WSAPI_Register message in order to
    define an action that allows WebSTAR to call your plug-in. These actions are temporary and
    only exist while your plug-in is active. actionTag is the name of the action that will
    show up in Admin's transfer type pop-up. pluginName is a string that names your code
    fragment. Both values should be unique among all plug-ins and may be the same value.
*/

WSAPI_ErrorCode WSAPI_RegisterSuffix (WSAPI_CommandPBPtr pb, char *actionTag, char *suffix,
                                        OSType fileType, OSType creatorType, char *mimeType);
/*    Your plug-in can call this routine in response to the WSAPI_Register message in order to
    define suffix mappings that allows the server will use with your plug-in.
    These suffix mappings are temporary and only exist while your plug-in is active.
    actionTag is the name of the action that will be invoked when a given suffix mapping
    show up in Admin's transfer type pop-up. The suffix parameter is the string that the server
    will match (e.g., ".html") to invoke the specified action.
    The next two fields are machine-specific and make sense on Macs only. The last parameter is
    the MIME type to send with this transfer.
*/

WSAPI_ErrorCode WSAPI_RegisterAccessControl (WSAPI_CommandPBPtr pb);
/* ## By making this call, your plug-in is registered as a handler for access control checks. There
    may be more than one access control handler. Your plug-in will receive a WSAPI_AccessControl message
    when appropriate. You should evaluate the URL and any other information necessary to determine whether or
    not access should be granted. Fill in the accessControl parameter block fields accordingly. If accessGranted
    is false, the server will refuse to allow access to that URL and if authRequired is true, it will return an
    appropriate HTTP response to cause the client to prompt for a username and password.
    Note that you are running as a "pre-" preprocessor and should not attempt to access data from the HTTP stream
    or otherwise manipulate information that may affect subsequent processing of the URL. Also, the first
    access control plug-in to refuse access terminates the access control checks, so it's not always the case
    that you will receive every WSAPI_AccessControl message, especially if there are other access control
    handlers installed before yours.
*/

WSAPI_ErrorCode WSAPI_RegisterFilter (WSAPI_CommandPBPtr pb);
/* ## By making this call, your plug-in is registered as a filter for incoming HTTP requests. You will be
    sent the WSAPI_Filter message and a PB structure (WSAPI_FilterPB) that contains a pointer to the complete
    HTTP request and its length. This includes all header info up to and including the CRLF CRLF separator between
    the HTTP request and the HTTP object body (if any).

    You will receive this message BEFORE the server has interpreted the contents of the HTTP request.
    You may read any info you'd like from this request buffer, but may not modify its contents.
    You may also create a new buffer using WSAPI_AllocateMemory and populate it with a new HTTP
    request to be interpeted by the server. Since multiple filters may be installed, there is no guarantee what
    order you will be called in or whether or not subsequent modifications will be made to the request you generate.
    By setting the newRequest field to a value other than null, you inform the server that it should use your
    request instead of the one received from the client. You MUST create a legal HTTP 1.0 request header and
    include the CRLF CRLF separator at the end of the request.
    The server is responsible for deallocating this new request buffer when done.
*/

/*********************/
/* security services */

WSAPI_ErrorCode WSAPI_ValidateUser (char *name, char *passwd, char *realm);
/*    Using the piUserKeyword, piPasswordKeyword, and piCurrentRealm fields, you can validate whether or not a specific
    user should be allowed access. You may substitute your own values in place of any of the predefined parameters
    if desired. (e.g., pass your own realm string instead of checking only for the current realm.)

    Returns WSAPI_I_NoErr if the user, password, and realm are OK. Returns WSAPI_I_NoPermission if the validation
    fails for any reason. Note that this call will return WSAPI_E_MessageNotHandled if an external function is
    providing security controls for the server (e.g., a security plug-in).
*/

/*************************/
/** AppleEvent Services **/

// routines for registering event handlers, sending events, etc.

WSAPI_ErrorCode WSAPI_SendIPCMessage (WSAPI_CommandPBPtr pb, void *msg);
/*    Sends an async, platform-specific interprocess communication message (e.g., AppleEvent on a Mac) that your
    plug-in has already constructed. For Mac O/S, pass a pointer to the AppleEvent structure you wish to send.

    IMPORTANT for WebSTAR Mac plug-ins!!!!
    For WebSTAR plug-ins, the server generates the appropriate return ID for your AppleEvent, so the value you
    supply to the AECreateAppleEvent call will be overwritten. If you are making this call as part of processing a
    message other than "Run" (i.e., that is NOT associated with a HTTP connection), you should note that your
    plug-in can have at most one pending event because ALL of your other message handlers run in a separate context
    from a HTTP connection and share a single return ID that WebSTAR uses to connect the asynch event reply to your
    plug-in.

    You are responsible for disposing any platform-specific data associated with your message after it
    has been sent (i.e., the event and address descriptors on Macs).
*/

WSAPI_ErrorCode WSAPI_WaitForIPCReply (WSAPI_CommandPBPtr pb, WSAPI_IPC_ResultPtr *msg);
/*    If you send an interprocess communication message (e.g., an AppleEvent under Mac O/S) and expect
    and asynchronous reply received by and delivered through the server to your thread of execution, you
    should call this routine once you expect the reply (i.e., after you've sent the IPC message). If the
    server receives the message reply before the timeout period defined by the server, your reply will be
    returned in the msg parameter. If not, msg will be null and an error code will be returned by the function.

    IMPORTANT for WebSTAR Mac plug-ins!!!!
    When the AppleEvent is returned to you, you MUST resume the AppleEvent with a call to AEResumeTheCurrentEvent.
    (See IM VI, 6-84) This will pass control to the handler you specify (should be a UPP to a procedure in your
    plug-in.) The handler must process the AE to completion. It is VERY important that your plug-in do this in
    a timely fashion and NOT yield time to other threads. (Well, yielding seems like a bad thing at this point
    because it might allow another plug-in to begin processing an event in parallel, and the AE manager is NOT
    reentrant and cannot process 2 events at once!) This means no callbacks until the event is handled!

    If msg is not null, you are responsible for disposing the msg data structure, plus any data passed to
    you in it if necessary.
*/

/*************************/
/**  Logging Services   **/

//TBS - routines for making log entries, processing log data, etc.

WSAPI_ErrorCode WSAPI_WriteLogEntry (WSAPI_CommandPBPtr pb, char *pluginName, char *msg);
/*    Writes the contents of msg to the server's log file. msg should be a null terminated
    C string. pluginName is a C string (generally your plug-in's name) that will prefix the log entry.
    The combined length of pluginName and msg should be less than 510 characters.
*/


/*************************/
/** Status Msg Services **/

WSAPI_ErrorCode WSAPI_DisplayMessage (WSAPI_CommandPBPtr pb, char *msg);
/*
    Writes the contents of msg on the server's status window. msg should be a null terminated
    C string.
*/


/**************************************/
/** User-supplied dispatcher routine **/

WSAPI_ErrorCode WSAPI_Dispatch (WSAPI_CommandPBPtr command);
/*    You must define this routine, which will be called from the WebSTAR Plug-in Framework
    library with a complete WSAPI_CommandPB record passed to your routine.
*/

#ifdef __cplusplus
}
#endif

#if GENERATINGPOWERPC
#pragma options align=reset
#endif

#endif